import { type AtomConfig, type AtomType } from "../atom/atom";
/**
 * A reactive `Map<string, T>` with optional per-entry TTL auto-expiry.
 *
 * Extends the base `AtomType` interface (minus `set` and `update`, which are
 * replaced by the higher-level mutation methods below).  Calling the atom as
 * a function — `cache()` — returns the underlying `Map<string, T>` and
 * registers the caller as a reactive subscriber, exactly as a plain atom would.
 *
 * @template T  The type of values stored in the cache.
 *
 * @example
 * ```ts
 * interface User { name: string }
 *
 * const userCache = cacheAtom<User>();
 *
 * // Permanent entry
 * userCache.add("u2", { name: "Bob" });
 *
 * // Entry that expires after 30 s
 * userCache.add("u1", { name: "Alice" }, 30_000);
 *
 * console.log(userCache.get("u1")); // { name: "Alice" }
 * console.log(userCache.size);      // 2
 * console.log(userCache.getAll());  // [{ name: "Alice" }, { name: "Bob" }]
 *
 * // Manual eviction
 * userCache.remove("u2");           // true
 *
 * // Replace an entry — existing timer is cancelled automatically
 * userCache.add("u1", { name: "Alice Updated" }, 60_000);
 *
 * // Wipe everything
 * userCache.clearAll();
 * ```
 */
export type CacheAtomType<T> = Omit<AtomType<Map<string, T>>, "set" | "update"> & {
    /**
     * Inserts or replaces an entry in the cache.
     *
     * - If `id` already exists any pending expiry timer is cancelled first.
     * - If `ttl` is a positive number the entry is automatically removed after
     *   `ttl` milliseconds.
     * - If `ttl` is `-1` or omitted the entry is permanent until manually
     *   removed or `clearAll()` is called.
     *
     * Notifies all subscribers after the mutation.
     *
     * @param id    Unique string key for the entry.
     * @param value Value to store.
     * @param ttl   Time-to-live in milliseconds (`> 0`), or `-1` / omitted for
     *              a permanent entry.
     */
    add(id: string, value: T, ttl?: number): void;
    /**
     * Returns the cached value for `id`, or `undefined` when absent.
     *
     * Registers the calling reactive context as a subscriber.
     *
     * @param id  Key to look up.
     */
    get(id: string): T | undefined;
    /**
     * Removes a single entry from the cache.
     *
     * Cancels any pending expiry timer and notifies subscribers.
     * Returns `false` — without emitting a notification — when `id` is not
     * present, keeping the behaviour consistent with `Map.prototype.delete`.
     *
     * @param id  Key to remove.
     * @returns   `true` if the entry existed and was removed; `false` otherwise.
     */
    remove(id: string): boolean;
    /**
     * Returns whether `id` currently exists in the cache.
     *
     * Registers the calling reactive context as a subscriber.
     *
     * @param id  Key to test.
     */
    has(id: string): boolean;
    /**
     * Returns a snapshot of all cached values as an ordered array.
     *
     * The order reflects the insertion order of the underlying `Map`.
     * Registers the calling reactive context as a subscriber.
     */
    getAll(): T[];
    /**
     * Clears the entire cache, cancels every pending expiry timer, and notifies
     * all subscribers.
     *
     * Called automatically when the component that created this atom unmounts.
     * At module level it must be called manually.
     */
    clearAll(): void;
    /** Reactive number of entries currently held in the cache. */
    readonly size: number;
    /** Discriminator tag — always `"cacheAtom"`. */
    readonly name: "cacheAtom";
};
/**
 * Creates a reactive `Map<string, T>` cache atom with optional per-entry TTL
 * auto-expiry.
 *
 * The returned object is callable (`cache()`) — invoking it returns the
 * underlying `Map<string, T>` and registers the caller as a reactive subscriber
 * in exactly the same way a plain `atom` would.
 *
 * **Automatic cleanup** — when `cacheAtom` is created inside a component's
 * outer function, `clearAll()` is registered as a teardown handler via
 * `registerCleanup`. On component unmount every pending TTL timer is cancelled
 * and all entries are removed automatically. When created at module level no
 * automatic cleanup occurs and `clearAll()` must be called manually if needed.
 *
 * Internally the factory:
 * 1. Creates a real `Map<string, T>` (`_map`) as the atom's initial value so
 *    that `cache()` always returns the same Map reference.
 * 2. Wraps it in a base `atom` whose identity drives all reactivity.
 * 3. Captures the original `base.get` **before** overriding `.get` on the
 *    result object, preventing infinite recursion in subscription-tracking
 *    calls.
 * 4. Attaches all extended methods via `(result as any).method = ...`
 *    following the `paginationAtom` pattern.
 * 5. Exposes `name`, `size`, `__isAtom___`, and `__version__` as
 *    `Object.defineProperty` getters following the `mapAtom` pattern.
 * 6. Calls `registerCleanup(base, clearAll)` — a no-op at module level,
 *    but hooks into the component host's teardown when called inside a
 *    component.
 *
 * @template T      The type of values stored in the cache.
 * @param   config  Optional atom configuration forwarded to the base `atom`.
 * @returns         A fully-reactive {@link CacheAtomType} instance.
 *
 * @example
 * ```ts
 * // Module level — manual clearAll required
 * const tokenCache = cacheAtom<string>();
 * tokenCache.add("jwt", "eyJ...", 15 * 60 * 1000); // expires in 15 min
 * tokenCache.add("refresh", "abc123");              // permanent
 *
 * effect(() => {
 *   console.log("cache size:", tokenCache.size);    // reactive
 * });
 *
 * // Inside a component — clearAll is called automatically on unmount
 * const MyComponent = view(() => {
 *   const recent = cacheAtom<Post>();
 *   recent.add("p1", post, 60_000);
 *   // …no manual cleanup needed
 * });
 * ```
 */
export declare function cacheAtom<T>(config?: AtomConfig): CacheAtomType<T>;
//# sourceMappingURL=cacheAtom.d.ts.map